40.1 Single Shell Commands

M-! (shell-command) reads a line of text using the minibuffer and executes it as a shell command, in a subshell made just for that command. Standard input for the command comes from the null device. If the shell command produces any output, the output appears either in the echo area (if it is short), or in an Emacs buffer named *Shell Command Output*, displayed in another window (if the output is long).

For instance, one way to decompress a file named foo.gz is to type M-! gunzip foo.gz RET. That shell command normally creates the file foo and produces no terminal output.

A numeric argument to shell-command, e.g., M-1 M-!, causes it to insert terminal output into the current buffer instead of a separate buffer. It puts point before the output, and sets the mark after the output. For instance, M-1 M-! gunzip < foo.gz RET would insert the uncompressed form of the file foo.gz into the current buffer.

Provided the specified shell command does not end with ‘&’, it runs synchronously, and you must wait for it to exit before continuing to use Emacs. To stop waiting, type C-g to quit; this sends a SIGINT signal to terminate the shell command (this is the same signal that C-c normally generates in the shell). Emacs then waits until the command actually terminates. If the shell command doesn’t stop (because it ignores the SIGINT signal), type C-g again; this sends the command a SIGKILL signal, which is impossible to ignore.

A shell command that ends in ‘&’ is executed asynchronously, and you can continue to use Emacs as it runs. You can also type M-& (async-shell-command) to execute a shell command asynchronously; this is exactly like calling M-! with a trailing ‘&’, except that you do not need the ‘&’. The default output buffer for asynchronous shell commands is named ‘*Async Shell Command*’. Emacs inserts the output into this buffer as it comes in, whether or not the buffer is visible in a window.

If you want to run more than one asynchronous shell command at the same time, they could end up competing for the output buffer. The option async-shell-command-buffer specifies what to do about this; e.g., whether to rename the pre-existing output buffer, or to use a different buffer for the new command. Consult the variable’s documentation for more possibilities.

M-| (shell-command-on-region) is like M-!, but passes the contents of the region as the standard input to the shell command, instead of no input. With a numeric argument, it deletes the old region and replaces it with the output from the shell command.

For example, you can use M-| with the gpg program to see what keys are in the buffer. If the buffer contains a GnuPG key, type C-x h M-| gpg RET to feed the entire buffer contents to gpg. This will output the list of keys to the *Shell Command Output* buffer.

The above commands use the shell specified by the variable shell-file-name. Its default value is determined by the SHELL environment variable when Emacs is started. If the file name is relative, Emacs searches the directories listed in exec-path (see Shell).

To specify a coding system for M-! or M-|, use the command C-x RET c immediately beforehand. See Communication Coding.

By default, error output is intermixed with the regular output in the output buffer. But if you change the value of the variable shell-command-default-error-buffer to a string, error output is inserted into a buffer of that name.